Editing Wiki with Visual Studio Code

Visual Studio Code Installation

Install Visual Studio Code

Download

• Visual Studio Code

Description

Visual Studio Code is a light-weight but powerful code editor from Microsoft.

Install Visual Studio Code Extensions

1. Foam for Gollum

Download

• Foam for Gollum

Features

• Gollum-style wikilinks — [[Alias|Page Name#section-heading]]
• Custom file dropdown provider — Places files and images automatically under a Gollum-style uploads folder
• Auto-completion — Auto-completes page names and section headings

2. Markdown All in One

Download

• Markdown All in One

Features

• Markdown keyboard shortcuts
• Math support in the preview pane
• And many more…

3. LTeX+

Download

• LTeX+

Features

• English-language spell checking in Markdown documents

Add Shortcuts to User Settings (Optional)

Click Ctrl+Shift+P and search for:

• Markdown All in One: Toggle Code Span, and click the gear icon and set its key binding to Win+Shift+C.
• Markdown All in One: Toggle Code Block, and click the gear icon and set its key binding to Win+Alt+C.

Accessing the Repository

Install Git

1. Download Git.
2. Install Git.

Install GitHub Desktop (Optional)

You can also install GitHub Desktop for a GUI.

Cloning Repository

(Use these instructions if you have write rights to the GnollHack Wiki repository. They can be granted by Sound Mind Games admins.)

1. Open your terminal (e.g. PowerShell or bash).
2. Go to the directory under which you want to clone GnollHack wiki, e.g. type cd C:\repos. If the directory does not exist, you must create it.
3. Type git clone https://github.com/hyvanmielenpelit/GnollHackWiki.git and press Enter.
4. GnollHack wiki should now install to the GnollHackWiki subdirectory.

Forking Repository and Making Pull Request

(Use these instructions if you don't have write rights to the GnollHack Wiki repository but you want to do a contribution.)

1. Go to the GnollHackWiki repository on GitHub.
2. Fork the repository by clicking the Fork badge.
   
3. Clone the forked repository to the local machine.
4. Make changes and commit them.
5. Push changes the forked repository.
6. Make a pull request to the GnollHack Wiki repository from the forked repository on GitHub.

You can read more about forking repositories and making pull requests in GitHub documentation: Creating a pull request from a fork.

Editing Conventions

Place Empty Line Around Headings

• Please use an empty line before all headings, except in the very beginning of a file.
• Please use an empty line after all headings.

Example

# Heading1

Some text

## Heading2

Some text

Use Subdirectories When Necessary

You should use subdirectories in the following cases:

1. Logical grouping of a large number of files.
   • There's a soft limit of 1000 files per directory on GitHub, after which directory listings are cut short.
2. To prevent naming conflicts.
   • For example, to differentiate between Grand Master monster and Grand Master difficulty.

Uploads Should Go Under /uploads/

Uploads, such as images, should be placed under /uploads/. If the document with an upload is in a subdirectory, the subdirectory name should also be included in the path. This should be handled automatically by Visual Studio Code, when you have the Foam for Gollum extension installed with the default settings.

Examples

• /uploads/Races/Dwarf/image.webp — An image in Races/Dwarf.
• /uploads/Home/image.webp — An image in Home.

Use Only WebP Files as Images

Please use WebP encoded at 85 quality as the image file format. Many image editing software support WebP.

• Adobe Photoshop has native WebP support since February 2022.
• For earlier versions of Adobe Photoshop and Adobe Photoshop Elements, you can download WebPShop plugin.

WebP Batch Conversion

You can use an online service to convert your images to WebP in one batch:

1. Go to To WebP website with your browser.
2. First, before adding files, set Quality to 85 and Size to whatever scaling factor you want to use for your images.
3. Click Add Files and select all files you want to convert.
4. Click Download All to download all images in WebP format in a ZIP file.

Image Size of Illustrative Images

Please use 512x512 pixel resolution for illustrative images and use 12.5 pixel rounded corners (you need to do rounded corners in an image editing software). Please try to keep their size under 100 KB. If it goes over 100 KB, you can try to reduce their image quality to 80.

Page Title Can Be Customized Using H1 Heading (#) in First Line

Page titles can be customized using an H1 heading (single #) in the first line of a page.

Example

# My Custom Page Title

Use Only H2 (##) and Lower Headings

Since the H1 heading (#) is reserved for customizing page titles, please use only H2 (##) and lower headings as section headings in a page.

Don't Put Anything Under /gollum/

/gollum/ folder is reserved for the Gollum wiki software functions. Please don't create that folder and don't put anything under it.

/.gollum/ Folder Is Reserved for Website Files

/.gollum/ (note the dot . in the folder name) is reserved for website specific files that are not related to wiki pages. Please place all files that are related to the wiki website development under it. However, if you are only adding content to the wiki, you should not touch the files under /.gollum/.

How-To-Do Guide

Open Markdown Preview

Press Ctrl+Shift+V.

Creating New Page from Wiki Link

You can create a new Markdown page by holding Ctrl down while clicking a wiki link (e.g. [[New Page]]).

Add File or Image

1. Start dragging a file or an image in File Explorer.
2. Before dropping hold Shift down.
3. Drop the file into a Markdown file.
4. It should automatically upload it and create an appropriate tag for it.

Add Unknown Word to Dictionary

1. Click a word with blue wavy underlining.
2. Click the yellow light bulb (quick fix) that appears near the left side of the line.
3. Choose Add 'word' to dictionary in the dropdown.

Publish Changes

1. Commit changes using the Source Control view.
2. Sync them.
3. If you updated the GnollHack Wiki repository directly, it takes up to 5 minutes for the changes to appear online.

Additional Information

Case-Insensitive Wikilinks

Wikilinks are case-insensitive, so you can write [[/Items/potion of healing]] and it works like this:

• potion of healing

It links to Potion of healing.

Case-Insensitive File Names

Note that file names are case-insensitive. Once you have committed a file into the wiki repository, you can't change its casing, which means you can't change the casing in the page title. In the case you have wrongly cased a file name, we recommend that you use an H1 heading to specify the right casing for the page title.

Global Tag Lookup Disabled

Global tag lookup is disabled, so you need to specify the exact path to the Markdown file.

No Need to Specify .md Extension for Markdown Files

Even though browser URLs in the wiki have the .md extension, you don't need to use it in wikilinks.

Wikilinks Relative to Current Document Directory

All wikilinks are relative to the current document directory and not to the root directory of the wiki (as in MediaWiki), making things a bit harder than necessary. However, you can just use / at the start of wikilinks to make them relative to the root directory. We have adopted a convention to always use it before subdirectories, but you may need to use it when referring to a file in the root directory, when the current document is in a subdirectory.

Changing Image and File Dropdown Templates

Gollum supports three syntaxes for image and file links. When you drop a file or image into a Markdown document while having the custom file dropdown provider enabled, Visual Studio Code will create a template based on the chosen syntax. You can set your preferred syntax in:

• User settings: The settings will be global to all your repositories.
• Workspace settings: The settings will be specific to a repository.

Applying settings this way is useful when you have repositories using different syntaxes and conventions and your preferred settings vary across repositories.

Image Templates

Based on the "foam.fileDropdown.imageTemplateFormat" setting, the custom file dropdown provider will generate the following templates.

Syntax	Setting Value	Template
Markdown	"markdown"	
HTML	"html"	<img src="/path/image.webp" alt="Text" width="Width" height="Height" />
Gollum	"gollum"	[​[/path/image.webp|alt=Text, width=Width, height=Height]​]

The default setting is "markdown".

File Templates

Based on the "foam.fileDropdown.fileTemplateFormat" setting, the custom file dropdown provider will generate the following templates.

Syntax	Setting Value	Template
Markdown	"markdown"	[Text](/path/file.pdf)
HTML	"html"	<a href="/path/file.pdf"/>Text</a>
Gollum	"gollum"	[​[Text|/path/file.pdf]​]

The default setting is "markdown".